/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import java.io.IOException;
import java.util.Enumeration;
import java.util.Properties;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanInitializationException;
import org.springframework.core.Ordered;
import org.springframework.core.PriorityOrdered;
import org.springframework.core.io.support.PropertiesLoaderSupport;
import org.springframework.util.ObjectUtils;

/**
 * <p>
 *     PlaceholderConfigurerSupport 和 PropertiesLoaderSupport 是 Spring 框架中用于配置管理和属性加载的两个支持类。它们提供了基础功能，使得开发者可以更方便地管理应用程序的外部化配置和属性文件。
 *     下面是对这两个类的功能分析以及它们如何帮助简化配置管理。
 *
 * 1. PlaceholderConfigurerSupport
 * 	功能
 * 		占位符解析：PlaceholderConfigurerSupport 是一个抽象类，它为解析配置文件中的占位符（如 ${propertyKey}）提供了支持。它通常通过子类实现，例如 PropertyPlaceholderConfigurer 或 PropertySourcesPlaceholderConfigurer，这些子类负责具体加载属性源并解析占位符。
 * 		默认值支持：支持定义占位符的默认值，即当指定的属性不存在时使用默认值。例如 ${propertyKey:defaultValue}。
 * 		系统属性和环境变量：能够访问系统属性（System.getProperties()）和环境变量（System.getenv()），并将它们作为属性源的一部分。
 * 		多属性源支持：可以从多个属性源加载属性，包括文件、URL、classpath 资源等，并按照一定的顺序进行解析。
 *	主要方法
 * 		resolvePlaceholder(String placeholder, Properties props)：解析给定的占位符字符串。
 * 		processProperties(ConfigurableListableBeanFactory beanFactory, Properties props)：处理属性集合，将其中的属性注册到 Bean 工厂中。
 * 		convertPropertyValue(String originalValue)：转换属性值，比如从字符串格式转换为实际的数据类型。
 *
 * 使用场景
 * 		外部化配置：当需要将应用程序的配置信息从代码中分离出来，放到外部属性文件中时，PlaceholderConfigurerSupport 及其子类可以帮助你轻松地加载和解析这些配置。
 * 		占位符替换：在配置文件或代码中使用占位符来引用属性值，可以在运行时动态地替换这些占位符为实际的属性值。
 * 		国际化和本地化：结合 Spring 的消息资源机制，可以通过占位符加载不同语言版本的消息文本。
 *
 * 2. PropertiesLoaderSupport
 * 	功能
 * 		属性文件加载：PropertiesLoaderSupport 提供了加载 .properties 文件的基本功能。它允许开发者指定属性文件的位置，并自动将其加载到内存中作为一个 Properties 对象。
 * 		多文件支持：支持同时加载多个属性文件，这些文件可以位于不同的位置，如文件系统、classpath 或 URL。
 * 		覆盖规则：如果存在同名属性，可以根据加载顺序决定哪一个属性值会被保留。通常情况下，后加载的文件会覆盖之前加载的相同属性。
 *		编码支持：提供对不同字符编码的支持，确保正确读取非 ASCII 字符。
 *
 * 	主要方法
 * 		setLocations(Resource... locations)：设置要加载的资源位置数组，可以是文件路径、classpath 资源或 URL。
 * 		loadProperties(Properties props)：执行属性文件的加载操作，并将结果存储在给定的 Properties 对象中。
 * 		mergeProperties()：合并所有加载的属性，返回一个包含所有属性的 Properties 对象。
 *
 * 	使用场景
 * 		配置管理：用于加载应用程序所需的配置信息，如数据库连接字符串、服务器端口等。
 * 		国际化资源：加载不同语言的消息资源文件，以便根据用户的语言环境显示合适的内容。
 * 		模块化配置：对于大型项目，可能需要将配置拆分为多个文件，每个文件负责一部分配置项。PropertiesLoaderSupport 可以帮助有效地管理和加载这些分散的配置文件。
 *
 * </p>
 * Allows for configuration of individual bean property values from a proper	ty resource,
 * i.e. a properties file. Useful for custom config files targeted at system
 * administrators that override bean properties configured in the application context.
 *
 * <p>Two concrete implementations are provided in the distribution:
 * <ul>
 * <li>{@link PropertyOverrideConfigurer} for "beanName.property=value" style overriding
 * (<i>pushing</i> values from a properties file into bean definitions)
 * <li>{@link PropertyPlaceholderConfigurer} for replacing "${...}" placeholders
 * (<i>pulling</i> values from a properties file into bean definitions)
 * </ul>
 *
 * <p>Property values can be converted after reading them in, through overriding
 * the {@link #convertPropertyValue} method. For example, encrypted values
 * can be detected and decrypted accordingly before processing them.
 *
 * @author Juergen Hoeller
 * @since 02.10.2003
 * @see PropertyOverrideConfigurer
 * @see PropertyPlaceholderConfigurer
 */
public abstract class PropertyResourceConfigurer extends PropertiesLoaderSupport
		implements BeanFactoryPostProcessor, PriorityOrdered {

	private int order = Ordered.LOWEST_PRECEDENCE;  // default: same as non-Ordered


	/**
	 * Set the order value of this object for sorting purposes.
	 * @see PriorityOrdered
	 */
	public void setOrder(int order) {
		this.order = order;
	}

	@Override
	public int getOrder() {
		return this.order;
	}


	/**
	 * {@linkplain #mergeProperties Merge}, {@linkplain #convertProperties convert} and
	 * {@linkplain #processProperties process} properties against the given bean factory.
	 * @throws BeanInitializationException if any properties cannot be loaded
	 */
	@Override
	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
		try {
			Properties mergedProps = mergeProperties();

			// Convert the merged properties, if necessary.
			convertProperties(mergedProps);

			// Let the subclass process the properties.
			processProperties(beanFactory, mergedProps);
		}
		catch (IOException ex) {
			throw new BeanInitializationException("Could not load properties: " + ex.getMessage(), ex);
		}
	}

	/**
	 * Convert the given merged properties, converting property values
	 * if necessary. The result will then be processed.
	 * <p>The default implementation will invoke {@link #convertPropertyValue}
	 * for each property value, replacing the original with the converted value.
	 * @param props the Properties to convert
	 * @see #processProperties
	 */
	protected void convertProperties(Properties props) {
		Enumeration<?> propertyNames = props.propertyNames();
		while (propertyNames.hasMoreElements()) {
			String propertyName = (String) propertyNames.nextElement();
			String propertyValue = props.getProperty(propertyName);
			String convertedValue = convertProperty(propertyName, propertyValue);
			if (!ObjectUtils.nullSafeEquals(propertyValue, convertedValue)) {
				props.setProperty(propertyName, convertedValue);
			}
		}
	}

	/**
	 * Convert the given property from the properties source to the value
	 * which should be applied.
	 * <p>The default implementation calls {@link #convertPropertyValue(String)}.
	 * @param propertyName the name of the property that the value is defined for
	 * @param propertyValue the original value from the properties source
	 * @return the converted value, to be used for processing
	 * @see #convertPropertyValue(String)
	 */
	protected String convertProperty(String propertyName, String propertyValue) {
		return convertPropertyValue(propertyValue);
	}

	/**
	 * Convert the given property value from the properties source to the value
	 * which should be applied.
	 * <p>The default implementation simply returns the original value.
	 * Can be overridden in subclasses, for example to detect
	 * encrypted values and decrypt them accordingly.
	 * @param originalValue the original value from the properties source
	 * (properties file or local "properties")
	 * @return the converted value, to be used for processing
	 * @see #setProperties
	 * @see #setLocations
	 * @see #setLocation
	 * @see #convertProperty(String, String)
	 */
	protected String convertPropertyValue(String originalValue) {
		return originalValue;
	}


	/**
	 * Apply the given Properties to the given BeanFactory.
	 * @param beanFactory the BeanFactory used by the application context
	 * @param props the Properties to apply
	 * @throws org.springframework.beans.BeansException in case of errors
	 */
	protected abstract void processProperties(ConfigurableListableBeanFactory beanFactory, Properties props)
			throws BeansException;

}
